CD ROM Paradise Collection 4/CD ROM Paradise Collection 4 1995 Nov.iso/asm/d86v401.zip/D05.DOC

Text File | 1994-12-21 | 19KB | 372 lines

CHAPTER 5   COMMAND LANGUAGE

In addition to immediate-execution assembly language commands,
there is a set of commands recognized by the debugger.  They are
identified by the first keyword on the line being a single letter
(i.e., the second character of the line is a non-letter, usually
a comma or ENTER).


General Operands to Debugger Commands

Most of the debugger commands consist of their single-letter
identifier, followed by a comma, followed by one or more general
operands, separated by commas.  General operands can be one of
the following:

   a. a numeric constant, whose format is just as in the assembly
      language (leading zero means default hex, otherwise default
      decimal)

   b. a register name

   c. a user symbol from the assembly language program being
      debugged.


Format of Debugger Command Examples

Many of the examples given below will be given in double quotes.
Note that the double quotes are not part of the command.  You are
encouraged to try out the example on the debugger, by typing the
string within the quotes, not including the quotes, and always
followed by the ENTER key. Note further that the double-quoted
string may be broken across two lines of this manual, but that
does not mean you should type an ENTER where the string is broken
--debugger commands always consist of a single line, always
terminated by ENTER.


The Debugger Command Set

Following is a description of the debugger commands recognized:

B  sets and clears the fixed breakpoints of the program.  The
   debugger has four breakpoints.  Two are transitory; they are
   automatically cleared after each return from the program to
   the debugger.  They can be set by the G command. The other two
   are fixed-- they will remain in effect until you explicitly
   clear them.  The fixed breakpoints are controlled by this B
   command.

   You follow the B with zero, one, or two general operands.  If
   there are zero operands (the B is followed immediately by an
   ENTER), then both fixed breakpoints are cleared.  If there are
   one or two operands, then the fixed breakpoints are set to the
   operands.
                                                              5-2

   Note that previously-set breakpoints can be implicitly
   cleared, by overwriting them with other breakpoints.  If your
   B command has one operand, and there was one breakpoint
   previously set, the debugger sets the unused breakpoint, so
   that both remain in effect.  If your B command has one
   operand, and both breakpoints were previously set, the most
   recently set breakpoint is saved, and the older breakpoint is
   overwritten.

   The status screen, displayed by typing Ctrl-S, shows you the
   B-command breakpoints in effect.

   Examples: if you type "b,numout", the debugger will set a
   breakpoint at location NUMOUT, which should be a label in the
   program being debugged. You may start and stop the program
   many times, and the breakpoint will stay there.  You may even
   allow the program to stop at NUMOUT repeatedly; the breakpoint
   is not cleared even if the program stops there.  If you
   subsequently type the command "b,01000", then there will be
   breakpoints at both NUMOUT and location hex 01000.  If you
   then type "b,01200", the first breakpoint NUMOUT is
   overwritten; the two breakpoints now in effect are 01000 and
   01200.  The 01000 breakpoint will be next in line to be
   overwritten.  You may clear both breakpoints by typing "b".
   There is no way to clear one breakpoint at a time.


D  sets or clears a data breakpoint.  This command is available
   only to registered D86 users running on a 386-based machine. A
   data breakpoint causes the program to trap to the debugger
   whenever a specified memory location is accessed.  The trap
   occurs after the instruction causing the access, so you should
   press the Up-arrow key to see the instruction.

   You follow the "D" with a comma, followed by a specification
   parameter.  The parameter consists of up to three characters,
   at most one each from the following categories:

   1. A letter giving the size of the memory element being
      checked: B for byte, W for word, D for doubleword, or a
      minus sign if you are clearing the breakpoint.  Default is
      B.

   2. The letter R if you wish to trap if the memory location is
      either written to or read from.  If you leave the R out,
      the trap will occur only if the memory location is written
      to.

   3. A digit, (0,1,2, or 3) giving the number of the 386
      breakpoint register you are using to set the trap.  Default
      is 0.
                                                              5-3

   You terminate the specification parameter with a comma, then
   provide one or two numbers to specify the memory location you
   are trapping. If you provide two numbers, the first is the
   segment register value and the second is the offset.  If you
   provide only one number, it is the offset-- the value of DS is
   used as the segment register value. As with all value
   parameters in D86, you can give a register name or a label
   instead of a number.  You can also leave out the address
   entirely, to preserve the previous address setting of that
   breakpoint register.

   Note that the 386 requires Word and Doubleword breakpoints to
   be aligned in memory.  If you provide an odd address for a
   Word breakpoint, the 386 will ignore the bottom bit of your
   address.  Similarly, the 386 will ignore the bottom two bits
   of your address for a Doubleword breakpoint.

   Examples: D,R1,ES,0400 sets a byte data read-or-write
   breakpoint, using the 386's register number 1, at memory
   location ES:0400.  D,-1 would clear that breakpoint.  D,R1
   would set it again with its previous value.  D,W,MY_VAR sets a
   Word breakpoint, using the 386's register number 0, at
   location DS:MY_VAR -- the trap will occur if either byte of
   the variable MY_VAR is written to (but MY_VAR should be
   aligned to an even address for this to work).

   If the D command is enabled, you'll get a one-line display of
   the data breakpoint registers in the status window (invoked
   via Ctrl-S).  The registers are presented in order: 0,1,2,3.
   The breakpoint type is given, followed by the 5-digit absolute
   memory address of the breakpoint.


F  finds a string of memory bytes.  The memory to be searched
   starts at the current CS:IP location.  The string being sought
   is contained in memory at the CS:IP location marked with the
   last Shift-F7 command.  The number of bytes in the target
   string is given as the first operand to the F command.  For
   example, "F,1" finds the next instance of a single byte value
   after the current CS:IP.  If the marked location points to a
   NOP, "F,1" will find the next NOP code.

   If you provide a second operand to F, it is a "retreat
   number".  For example, "F 2,10" assumes that you are looking
   for a 2-byte sequence, and you have retreated 10 bytes from
   the starting location for your search.  When the string is
   found, F will retreat 10 bytes from that string.  That way you
   can view the instructions that preceded the found string.  I
   use this feature when I am searching for BIOS and DOS
   interrupt calls in a program.  I want to retreat before the
   calls, to see what function numbers were loaded into
   registers.  I can use the F3 key to repeat the searches,
   giving me a sequence of disassembly displays with the
   interrupt in the middle.
                                                              5-4

   F with no operands returns CS:IP to the marked location, in
   case you want to use F7 to deposit another string to be
   searched.

   If you have never pressed Shift-F7 in this session, the marked
   location is 0C000 of the program's starting segment.  That's
   often a good "scratchpad" area for small programs, far from
   both the program and the stack.


G  starts the user program.  You can give one or two operands to
   G, specifying locations within the program at which you wish
   to return to the debugger.  These are "transitory
   breakpoints"; both of them are cleared when the program
   returns to the debugger for any reason.

   Whenever you start the program, at least one instruction from
   the program will be executed, even if there is a breakpoint at
   the current instruction pointer location.  This means you can
   set a breakpoint at the current location; instructing the
   program to return to the debugger the next time it gets back
   to the current location.


J  jumps to the location indicated by the operand, within the
   current code segment.  J is useful when you are exploring
   memory outside of your program's memory area.  In that case,
   the immediate JMP command is executed from a buffer within
   your program's original code segment.  JMP would therefore
   return you to that segment.  J will keep you in the distant
   segment.
                                                              5-5

K  allows you to save and play back D86 keystroke scripts.  D86
   records in memory all keystrokes (up to a limit of 1024) you
   type to the debugger, and lets you save those keystrokes in
   files, and recall them, in several different ways.  All D86
   keystroke script files have the extension D8K in their names.
   If D86 finds a script file whose root name is the same as the
   program being debugged, D86 will automatically play back that
   script as soon as it starts up.  You can use this feature to
   set up files (with the S command), set up memory displays, and
   step to the area of your program you are concentrating on,
   avoiding repetition every time you enter the debugger.  If you
   specify D86 without a program name, D86 will look for a script
   named NULL.D8K.  In either case, if D86 does not find the
   progname.D8K file, it will look for a file named D86.D8K and
   run that.  This allows you to set up a global-default
   keystroke script, to be used to start every debugging session.
   During a debugging session, you can play back keystroke
   scripts from the debugger command line with the K,P command
   described shortly, or at any time by pressing the Alt key
   together with any letter key. For example, Alt-L pressed at
   any time will play back the ALTL.D8K script.

   You can mark the beginning of the keystrokes to be saved in
   one of several ways.  The K,F command will flush all recorded
   keystrokes from D86's memory buffer, letting you "start
   fresh".  The S,F command also does this; it resets the entire
   debugging session as well (cancelling the effects of any
   default scripts or manually-typed keystrokes).  The Ctrl-M key
   can be typed in any debugger context to mark the beginning of
   keystrokes to be saved by the next save command, without
   actually flushing the previous keystrokes -- the debugger
   remains in whatever context it was in, the marker will revert
   to the start of the session after the next keystroke-save
   operation, and the Undo command will play back from the start
   of the session.

   The command K,S,filename will save debugger keystrokes in a
   file named filename.D8K ("filename" can be any name you wish,
   and you do not need to explicitly give the D8K extension in
   the command).  The file will begin with keystrokes marked by
   the last command described in the above paragraph; if no such
   specification was given, the file starts at the beginning of
   the entire debugger session. Commands and keys dealing with
   keystroke scripts are not themselves recorded.  If you issued
   a previous playback command, or if a playback occurred by
   default, the keystrokes from those playbacks are included as
   if you had typed them manually.
                                                              5-6

   Alternatively, you can save ALTx.D8K files from any debugger
   context by pressing the Ctrl-K key, followed by the Alt-key
   you wish to associate with the key sequence.  For example,
   suppose you wish to save the keystroke sequence for the
   memory-window specification for a complicated structure.  You
   wish the sequence to include the format of the structure, but
   not its location-specification.  You can do this by pressing
   Ctrl-M to mark the beginning of the recording, the digit 0 to
   move to the beginning of the first free memory window, the
   specification (e.g., B3WB1,), the Ctrl-K key, and the Alt-S
   key.  The debugger silently saves the keystroke sequence in a
   file called ALTS.D8K.  From now on, whenever you type the
   Alt-S key, the keystrokes 0B3WB1, will be played back, leaving
   you ready to type only the location where you want the memory
   structure to be displayed.

   The command K,P,filename will play back the keystroke script
   file filename.D8K that you previously saved.  This form, while
   more cumbersome to invoke, allows you to use a greater variety
   of file names.  All keystroke playback files can be either in
   the current directory, or any directory named in your PATH
   environment variable.


L  creates a disassembly listing, with addresses, hex bytes, and
   disassembled code.  You can output either the entire COM
   program, or a section of memory beginning with the current
   CS:IP location.  You omit the first operand if you want the
   entire COM program.  If you want a section of memory, you
   provide the offset beyond the memory section as the first
   operand.  You give the name of the output file for the listing
   as the second operand.  If you omit the second operand, the
   listing goes to the printer.  Examples: L,,FOO.LST outputs the
   entire COM program to FOO.LST.  L,0200,SEG.LST outputs the
   section of memory from CS:IP up to CS:0200 to SEG.LST.


O  sets a special fixed breakpoint.  Whenever your program calls
   MSDOS via INT 021, the debugger will monitor the function
   number passed in the AH register.  If the function number
   falls within the range specified by this command, the program
   will trap back to the debugger.  If you give two operands to
   O, the operands are the lower and upper bounds for the range
   of trapped functions.  If you give one operand, only that
   function number will be trapped.  If you give no operands, any
   previous O-trap setting is cleared.

   For example, note that function 3F hex is the READ function
   for MSDOS version 2.  If you want to trap whenever this READ
   function is invoked, you can issue the command O,03F and then
   start up your program with the G command.  Another example:
   suppose you want to insure that a program does not make any of
   the new Version 3 DOS calls, 59 hex and above.  You can issue
   the command O,059,0FF and then start your program.
                                                              5-7

   NOTE: if the second operand is less than the first, then the
   range wraps around through zero.  For example, O,059,030 traps
   on 059 through 0FF, and also 0 through 030-- both version 3
   and version 1 calls.

   SECOND NOTE: The EXIT function, hex 4C is always trapped by
   D86, regardless of your O-command settings.  The only way you
   should be able to exit from D86 is via the Q-command.  (If you
   do succeed in exiting some other way, I want to hear about it.
   In that case, D86 will become very confused if you reinvoke it
   before rebooting the computer.)


S    performs system functions, letting you bring your computer
   to a known state before debugging.  If the program you are
   debugging changes the contents of files on your computer, you
   may wish to begin your debugging session by restoring modified
   files from backup copies, and deleting any newly-created files
   from previous debugging sessions.  You can then save these
   commands in a keystroke script (see the K command), or perform
   an Undo command.

   The command S,C,srcfile,destfile copies the file named
   "srcfile" to the file named "destfile".  The command
   S,D,filename deletes the file named "filename".  The command
   S,R resets the debugging session: all open user files are
   closed, standard input and output are "rewound" if they had
   been redirected to disk files, the current drive and directory
   are restored, the debugged program is is reloaded from the
   disk, and the default keystroke script, if any, is rerun.  The
   command S,F does the same as S,R except the keystroke script
   is not rerun: this allows you to redefine what your starting
   script will be.


Q  exits the debugger and goes back to the operating system.


U    performs an "Undo" command by resetting and replaying your
   entire debugging session, except for the last commands.  The
   command U without any operands will retract a single command.
   The command U,number will retract the number of commands
   indicated.  For the purposes of this count, each full line
   typed to the debugger counts as a single command.  If you give
   a number bigger than the number of commands thus far issued,
   D86 will retract to the beginning of the debugging session.
   Retracted keystrokes can be replayed by pressing the Ctrl-R
   key (R stands for "Redo") repeatedly.
                                                              5-8

W  writes the program (if it was a COM format) and the symbol
   table back to the disk.  In this present version, you don't
   have any options as to what to name the files.  The program
   name given when D86 was invoked is always used, except that
   the files are always written to the current directory.  The
   program file has the same extension as the file that was
   loaded, and the symbols file has the SYM extension.

   D86 writes the program from location 0100 in the original code
   segment, up to the end-of-file location saved when the program
   was loaded, and possibly extended by a patch-memory operation
   while at the end of the program.  Any symbols added while in
   the patch-memory mode are saved in the symbols file, so that
   you can "reverse engineer" programs for which you do not have
   source, and save the symbol table results you have gleaned.